Authorization

Important! Basic authentication is currently deprecated for the Jumio REST APIs.

All calls to Jumio REST APIs should be authorized using OAuth2 Bearer Tokens. You obtain the bearer token by calling the Access Token URL (OAuth2) for your region with your API token and secret values, which you can find in the Customer Portal under:

Settings > Identity Verification > API credentials > OAuth2 Clients

Note: A transaction-specific token for uploading credentials and finalizing the workflow is generated for you when you create or update an account. These tokens are available in the response from the account create or account update call.

As a security best practice, requests for bearer tokens should be server-to-server, to avoid making your Client ID and Client secret values available to an end-user’s device. Regardless of the integration channel, the end-user’s device should notify your server when a token is required. Your server should make the call to the Jumio OAuth server, and then pass the token to the end-user device.

Client ID and Client secret are used to generate an OAuth2 access token. OAuth2 has to be activated for your account. Contact your Jumio Account Manager for activation. Access your Client ID and Client secret from the Portal. See API Credentials.

The TLS Protocol is required to securely transmit your data, and we strongly recommend using the latest version. For information on cipher suites supported by Jumio during the TLS handshake see Supported Cipher Suites.

Access Token URLs (OAuth2):

US: https://auth.amer-1.jumio.ai/oauth2/token
EU: https://auth.emea-1.jumio.ai/oauth2/token
SG: https://auth.apac-1.jumio.ai/oauth2/token

Calls with missing, incorrect or suspicious headers or parameter values will result in HTTP status code 400 Bad Request Error or 403 Forbidden.

oauth2/token requests are subject to Rate Limits. The default rate limit is 10 per second. If the rate limit is reached a HTTP 429 Too many requests status code is returned.

Example: Request Access Token

curl --location 'https://auth.amer-1.jumio.ai/oauth2/token'\
            -u CLIENT_ID:CLIENT_SECRET \
            --header 'Accept: application/json'\
            --data-urlencode 'grant_type=client_credentials'

Response

{
   "access_token": "YOUR_ACCESS_TOKEN",
   "expires_in": 3600,
   "token_type": "Bearer"
}

Access Token Timeout

The OAuth2 access token is valid for 60 minutes. After the token has expired it is necessary to generate a new access token.

Transaction Token Timeout

The transaction-specific token that is generated by the account create call or update call is valid for 30 minutes by default. It can be:

Configured via the Jumio Portal. See Application Settings.
Overwritten using the API call (tokenLifetime). See Creating or Updating Accounts.

Within this token lifetime the token can be used to initialize the SDK, API or Web journey.

As soon as the workflow (transaction) starts, a 15 minute session timeout starts. For each action performed (capture image, upload image) the session timeout will reset, and the 15 minutes will start again.